Add image template functions docs for EC v3#3940
Conversation
Document ReplicatedImageName, ReplicatedImageRegistry, ReplicatedImageRepository, ImagePullSecretName, and HelmValue template functions with recommended setup patterns for online and air gap installations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| ### ReplicatedImageRepository | ||
|
|
||
| ```go | ||
| func ReplicatedImageRepository(repository string, noProxy ...bool) string |
There was a problem hiding this comment.
its awkward reading go code here. its not obvious that noProxy is optional or what the intention of the ... is
There was a problem hiding this comment.
this matches our docs elsewhere for template functions...
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
| @@ -1,11 +1,11 @@ | |||
| For each image reference in your Helm chart values file, set the image repository URL to the location of the image in the proxy registry. | |||
| For each Helm chart used by your application, in the Helm chart's `values.yaml` file, update all references to private or third-party images to use the Replicated proxy registry domain. | |||
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
| These steps assume that you package your application with Helm and that you install with the [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource. | ||
|
|
||
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below. | ||
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
| These steps assume that you package your application with Helm and that you install with the [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource. | ||
|
|
||
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below. | ||
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below. |
There was a problem hiding this comment.
[Replicated.PositionalLanguage] Avoid spacial and directional language like 'below'. Instead, use 'on this page', 'the following', or link to the section.
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below. | ||
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below. | ||
|
|
||
| ### Embedded Cluster v3 (Beta) {#configure-v3} |
There was a problem hiding this comment.
[Replicated.Headings] 'Embedded Cluster v3 (Beta) ***************' should use sentence case.
| @@ -0,0 +1,212 @@ | |||
| # Image Template Functions for Embedded Cluster (Beta) | |||
There was a problem hiding this comment.
[Replicated.Headings] 'Image Template Functions for Embedded Cluster (Beta)' should use sentence case.
|
|
||
| - When referencing Docker Hub images through the Replicated proxy registry, use the full path including `docker.io` and the namespace. For official images, this means including `library`. For example, to proxy the `nginx` image, use `proxy.replicated.com/proxy/my-app/docker.io/library/nginx` (not `proxy.replicated.com/proxy/my-app/nginx`). For other Docker Hub images, include the organization (for example, `proxy.replicated.com/proxy/my-app/docker.io/bitnami/postgresql`). | ||
|
|
||
| ## Function Reference |
There was a problem hiding this comment.
[Replicated.Headings] 'Function Reference' should use sentence case.
|
|
||
| Returns a full image reference (registry + repository + tag). Use this when a chart expects the entire image reference in a single field. The optional `noProxy` parameter, when set to `true`, leaves the image unchanged in online mode. | ||
|
|
||
| | Mode | noProxy | Result | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?
|
|
||
| Returns the registry host. Use this when a chart splits the image reference into separate `registry` and `repository` fields. The optional `noProxy` parameter, when set to `true`, returns the input registry unchanged in online mode. | ||
|
|
||
| | Mode | noProxy | Result | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?
|
|
||
| Returns the repository path. Use this together with `ReplicatedImageRegistry`. The optional `noProxy` parameter, when set to `true`, returns the input repository unchanged in online mode. | ||
|
|
||
| | Mode | noProxy | Result | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?
|
|
||
| Returns the value from the chart's `values.yaml` at the given dotted path. Use this to read the chart's default image values and pass them to image template functions. | ||
|
|
||
| ## KOTS-Compatible Aliases |
There was a problem hiding this comment.
[Replicated.Headings] 'KOTS-Compatible Aliases' should use sentence case.
| @@ -0,0 +1,199 @@ | |||
| # Template Functions for Embedded Cluster (Beta) | |||
There was a problem hiding this comment.
[Replicated.Headings] 'Template Functions for Embedded Cluster (Beta)' should use sentence case.
| @@ -0,0 +1,199 @@ | |||
| # Template Functions for Embedded Cluster (Beta) | |||
|
|
|||
| This topic lists the Replicated template functions for Embedded Cluster. For more imformation about how to use Replicated template functions, including a list of all available template functions, see [About Template Functions](/reference/template-functions-about). | |||
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'imformation'?
| initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") true }}' | ||
| ``` | ||
|
|
||
| #### Return a value from a subchart |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'subchart'?
|
|
||
| ### Parameters | ||
|
|
||
| #### image |
There was a problem hiding this comment.
[Replicated.Headings] 'image' should use sentence case.
|
|
||
| Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path. | ||
|
|
||
| #### noProxy |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?
|
|
||
| ### Parameters | ||
|
|
||
| #### image |
There was a problem hiding this comment.
[Replicated.Headings] 'image' should use sentence case.
|
|
||
| Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path. | ||
|
|
||
| #### noProxy |
There was a problem hiding this comment.
[Replicated.Headings] 'noProxy' should use sentence case.
|
|
||
| Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path. | ||
|
|
||
| #### noProxy |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?
|
|
||
| #### noProxy | ||
|
|
||
| The following table describes the value returned by ReplicatedImageName in online or air gap installations, when the `noProxy` field is omitted or set to `true`: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is omitted').
|
|
||
| The following table describes the value returned by ReplicatedImageName in online or air gap installations, when the `noProxy` field is omitted or set to `true`: | ||
|
|
||
| | Install type | noProxy | Result | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?
|
|
||
| ### Parameters | ||
|
|
||
| #### image |
There was a problem hiding this comment.
[Replicated.Headings] 'image' should use sentence case.
| The image reference to rewrite. | ||
| Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path. | ||
|
|
||
| #### noProxy |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?
| The image reference to rewrite. | ||
| Use the [HelmValue](#helmvalue-func) function to return the value from the chart's `values.yaml` at the given dotted path. | ||
|
|
||
| #### noProxy |
There was a problem hiding this comment.
[Replicated.Headings] 'noProxy' should use sentence case.
|
|
||
| #### noProxy | ||
|
|
||
| The following table describes the value returned by ReplicatedImageName in online or air gap installations when the `noProxy` field is omitted or set to `true`: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is omitted').
|
|
||
| The following table describes the value returned by ReplicatedImageName in online or air gap installations when the `noProxy` field is omitted or set to `true`: | ||
|
|
||
| | Install type | noProxy | Result | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'noProxy'?
|
|
||
| #### noProxy | ||
|
|
||
| The following table describes the value returned by ReplicatedImageName in online or air gap installations, when the `noProxy` field is omitted or set to `true`: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is omitted').
| To create an application release that supports installation with Embedded Cluster v3: | ||
|
|
||
| To add the Embedded Cluster Config: | ||
| 1. If you use the Replicated proxy registry, update all references to private or third-party images to use the Replicated proxy registry domain. See the _Embedded Cluster v3_ steps in [Configure your application to use the proxy registry](/vendor/private-images-kots#configure-v3). |
There was a problem hiding this comment.
This links to the existing docs on how to rewrite image refs in your values file to use the proxy domain. I've updated those docs to add a new subsection for EC v3.
| * `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry. | ||
| - `DOMAIN` is either `proxy.replicated.com` or your custom domain | ||
| - `APP_SLUG` is the unique slug of your application | ||
| - `UPSTREAM_REGISTRY/IMAGE_PATH` is the full upstream image path. For example, `ghcr.io/my-org/my-image` or `docker.io/bitnami/postgresql`. |
There was a problem hiding this comment.
Updated this guidance to use "upstream" terminology instead of "external" based on Salah's language in embedded-image-template-functions.mdx
| * LocalImageName | ||
|
|
||
| These template functions are typically used to conditionally rewrite image references in air gap installations to reference the local image registry. For Embedded Cluster v3 installations, use the ReplicatedImageName, ReplicatedImageName, and ReplicatedImageName template functions instead. For more information, see [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). | ||
|
|
There was a problem hiding this comment.
^ Added this limitation to call out that the image temp funcs are not supported in ec v3 installations
|
|
||
| :::note | ||
| The LocalRegistryAddress template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). | ||
| ::: |
There was a problem hiding this comment.
added these notes to each of the unsupported image templates functions
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below. | ||
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below. | ||
|
|
||
| ### Embedded Cluster v3 (Beta) {#configure-v3} |
There was a problem hiding this comment.
Added these new steps for ECv3. The main difference is that you don't need to inject the image pull secret anymore since EC v3 automatically configures the cluster to authenticate to the proxy registry for all pods
| import RewriteHelmValues from "../docs/partials/proxy-service/_step-rewrite-helm-values.mdx" | ||
| import DependencyYaml from "../docs//partials/replicated-sdk/_dependency-yaml.mdx" | ||
|
|
||
| # Configure Embedded Cluster (Beta) |
There was a problem hiding this comment.
my goal with this page is that ECv3 vendors won't need to reference the existing https://docs.replicated.com/vendor/helm-native-v2-using in the KOTS docs in order to configure HelmChart v2 for ECv3 installations
| values: | ||
| initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") true }}' | ||
| ``` | ||
| ReplicatedImageName sets `noProxy` to `true` because the image reference value in `values.yaml` already contains the proxy path prefix (`proxy.replicated.com/proxy/my-app/...`) |
There was a problem hiding this comment.
I added a question here about when to use noProxy https://github.com/replicatedhq/replicated-docs/pull/3940/changes#r3070284069
| Image template functions automatically rewrite image references based on the installation mode: | ||
|
|
||
| - **Online**: Images are served through the Replicated proxy registry (`proxy.replicated.com` or your custom domain). Images that do not need to go through the proxy can be left unchanged using the `noProxy` parameter. | ||
| - **Air gap**: All images are rewritten to the local registry regardless of the `noProxy` parameter. |
There was a problem hiding this comment.
All images are rewritten to the local registry
Does this refer to the Embedded Cluster built-in local registry? Or are there cases where the user is able to bring their own local registry?
| |------|---------|--------| | ||
| | Online | Omitted | Returns the proxy registry URL for the image in the format: `proxy.replicated.com/proxy/<app-slug>/<image>`, where `app-slug` is the unique application slug | | ||
| | Online | `true` | Returns the image reference with no changes | | ||
| | Air gap | `true` or omitted | Returns the location of the image at the local image registry in the format: `<local-registry>/<app-slug>/<name>:<tag>` | |
There was a problem hiding this comment.
Does local-registry here always mean EC's built-in image registry? Or is the user able to bring their own local registry?
https://github.com/replicatedhq/replicated-docs/pull/3940/changes#r3070292020
| //REFERENCE DOCS | ||
| { type: "html", value: "<h5>Reference</h5>", defaultStyle: true }, | ||
| "embedded-config", | ||
| "template-functions", |
There was a problem hiding this comment.
moved these to a Reference section in the sidebar
Document ReplicatedImageName, ReplicatedImageRegistry, ReplicatedImageRepository, and HelmValue template functions with recommended setup patterns for online and air gap installations.